This document describes a simple interface for reading the system clock.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
The final implementations MAY decorate the objects with more functionality than the one proposed, but they MUST implement the indicated interfaces/functionality first.
Creating a standard way of accessing the clock would allow interoperability
during testing, when testing behavior that has timing-based side effects.
Common ways to get the current time include calling \time()
or
new \DateTimeImmutable('now')
. However, this makes mocking the current time
impossible in some situations.
Clock - The clock is able to read the current time and date.
Timestamp - The current time as an integer number of seconds since Jan 1, 1970 00:00:00 UTC.
Get the current timestamp
This should be done by using the getTimestamp()
method on the returned \DateTimeImmutable
:
$timestamp = $clock->now()->getTimestamp();
The clock interface defines the most basic operations to read the current time and date from the clock.
It MUST return the time as a \DateTimeImmutable
.
<?php
namespace Psr\Clock;
interface ClockInterface
{
/**
* Returns the current time as a DateTimeImmutable Object
*/
public function now(): \DateTimeImmutable;
}